home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2004 #2 / Amiga Plus CD - 2004 - No. 02.iso / AmiSoft / Misc / emu / Flamingo.lha / Flamingo / docs / XVD.txt < prev    next >
Text File  |  2000-07-23  |  8KB  |  240 lines
  1.  
  2. Flamingo Plus/4 emulator for the Amiga
  3. External video driver documentation
  4.  
  5. version 2.0
  6. Friday 21.07.2000
  7.  
  8. Intro
  9. -----
  10.  
  11.  As became an "industry standard" Flamingo have external driver for video.
  12. That is a must because of the mess of different Amiga video drivers, cards
  13. and other trouble makers, and because of my limited possibilities and
  14. abilities. I am not perfect, God knows, even you can write a much faster
  15. video driver than mine.
  16.  
  17.  To build a video driver for Flamingo is as easy as a pie. You have to obey
  18. some rules anyway, those are included in this text. Before you start coding
  19. anything please (PLEASE!) read this doc carefully!
  20.  
  21. Format
  22. ------
  23.  
  24.  As usual too external video drivers are executables, and loaded by LoadSeg,
  25. when needed. If your version is working on the PowerPC processor, you have
  26. use WarpUP, as FlamingoPPC works on this kernel. (Mixed binary preferred
  27. here!)
  28.  
  29.  To allow this you have to start with these lines (in that case, when anybody
  30. start it without Flamingo):
  31.  
  32.         moveq.l    #0,d0
  33.         rts
  34.  
  35.  Then you have to continue with a simple pattern for identify:
  36.  
  37.         dc.b 'FLAMINGOXVD'
  38.  
  39.  Next byte is for identify video-driver version level. This should be for
  40. now:
  41.  
  42.         dc.b '2'
  43.  
  44.  That was all about identify. Verison level will be raised if any changes
  45. should become in driver format later.
  46.  
  47.  Then a little table coming up:
  48.  
  49.         dc.l Name_of_video_driver     ; -> pointer
  50.         dc.l Author_of_video_driver   ; -> pointer
  51.         dc.w Version                  ; -> not pointer, but the number
  52.         dc.w Revision                 ; -> not pointer, but the number
  53.  
  54.  Name and Author strings should be zero terminated.
  55.  
  56.  And finally the table of pointers to the functions:
  57.  
  58.         dc.l drv_Init
  59.         dc.l drv_Done
  60.         dc.l drv_Configure
  61.         dc.l drv_OpenScreen
  62.         dc.l drv_CloseScreen
  63.         dc.l drv_Refresh
  64.         dc.l drv_RefreshPPC
  65.  
  66. Functions
  67. ---------
  68.  
  69.  At first: keep in mind code must be reentant. No global variables, memory
  70. array etc... Of course you have to hold your data somewhere, and this would
  71. be a memory segment allocated by your driver, and it will be given as
  72. parameter for every function of yours. (Let's call handler.) This handler
  73. should be given back by drv_Init_driver function.
  74.  Flamingo will never change this piece of memory. (Of course not, it knows
  75. nothing about it, even not the length.)
  76.  
  77.  You can mess up all registers Flamingo saves his regs before your routine
  78. will be called. All subroutines called by a JSR, so all have to end with RTS.
  79. (BLR for PPC Refresh.)
  80.  
  81.  Okay, let's go on with the functions:
  82.  
  83. * drv_Init *
  84.  
  85.  Inputs:
  86.    A0 - pointer to library bases
  87.    A1 - public screen (eg. Workbench)
  88.  
  89.  Outputs:
  90.    D0 - handler
  91.    D1 - ptr to message
  92.  
  93.  You can do anything in this function, initialisations, open libraries etc.
  94.  As input the routine will get a structure of longwords:
  95.  
  96.     dc.l  graphics_library_base
  97.     dc.l  dos_library_base
  98.     dc.l  intuition_library_base
  99.     dc.l  gadtools_library_base
  100.     dc.l  asl_library_base
  101.     dc.l  powerpc_library_base
  102.  
  103.  Do not open provided libraries use these bases! PowerPC.library base could
  104. be zero, that might mean no PPC available. Don't forget handle this. (Eg.
  105. checking at the start, and cancel the init.)
  106.  
  107.  As output give back any number in D0 except zero (0). This will be your
  108. handler, you may ignore it, if you need no room to store something (I can
  109. hardly believe).
  110.  Zero output means your driver was failed to initialize itself. (Missing
  111. driver, library etc.) In this case you can send a pointer to an  error message
  112. string in D1. It will be displayed in some way. (If D0 not zero D1 will be
  113. ignored.)
  114.  
  115. * drv_Done *
  116.  
  117.  Inputs:
  118.    A0 - handler
  119.  
  120.  Deallocate all system resources you have ever allocated. Do not call
  121. drv_CloseScreen from this routine, it will be called before! Don't forget
  122. deallocate all memory, even used by handler!
  123.  
  124. * drv_Configure *
  125.  
  126.  Inputs:
  127.    A0 - handler
  128.  
  129.  You can open an interface, if your driver needs any configuration. All 
  130. library bases (gadtools too) was given in drv_Init, do not reopen these!
  131.  The other parts of Flamingo are hanging while your configuration is running.
  132.  
  133.  Important! If this field in the structure contains zero, then configure
  134. button will be disabled in Flamingo's GUI. (Please put zero here, if you have
  135. nothing to configure.)
  136.  
  137. * drv_OpenScreen *
  138.  
  139.  Inputs:
  140.    A0 - handler
  141.    A1 - screen_params
  142.  
  143.  Output:
  144.    D0 - valid IDCMP port address
  145.    D1 - ptr to message
  146.    D2 - ptr to allocated chunky buffer
  147.    D3 - modulo for the chunky buffer (LONG)
  148.  
  149.  Open your screen by this routine. Screen_params is a structure to
  150.  
  151.     dc.w    xsize
  152.     dc.w    ysize
  153.     dc.l    palette            ;ptr to the palette
  154.  
  155.  xsize is screen width and always an even multiple of 16, ysize is screen
  156. height, palette a pointer to an array of RGB values on 8 bits per gun each
  157. (R1,G1,B1,R2,G2,B2,...) contains 121 colors. About screen format can be found
  158. more in refresh part.
  159.  If your routine was not able to open its screen, then send back 0 in D0, and
  160. you can also send some zero terminated string in D1 as an error message.
  161. (drv_Done called in this case too!)
  162.  If open was successful send a valid IDCMP port address in D0, D1 will be
  163. ingored.
  164.  The only IDCMP required by Flamingo is IDCMP_RAWKEY, other messages will be
  165. discarded.
  166.  Don't forget to allocate chunky buffer for the emulated screen! Give back
  167. this address in D2. (Size is xsize*ysize in bytes.) There is an easy way on
  168. graphcards doing double buffered chunky screens, by allocating both buffer
  169. and changing displayed at drv_Refresh. (Find out more at there.)
  170.  I added modulo for the chunky screen, as it might be useful for native
  171. chunky displays.
  172.  
  173. * drv_CloseScreen *
  174.  
  175.  Input:
  176.    A0 - handler
  177.  
  178.  Close your screen by this routine. (Or hide, if you prefer, but watch out on
  179. hide, drv_OpenScreen can be recall after drv_CloseScreen! And don't forget
  180. deallocate your screen on drv_Done...)
  181.  
  182. * drv_Refresh *
  183.  
  184.  Input:
  185.    A0 - handler
  186.  
  187.  Output:
  188.    D0 - (next) chunky screen
  189.  
  190.  This routine changed since the 2nd version of the XVD format. The pointer
  191. can b be 0, if your driver uses only the PowerPC routine and vice versa.
  192. Watch out! If both pointer non NULL, both will be called!
  193.  
  194.  Here you have to refresh your screen. If your driver is a graphcard driver
  195. which can set up chunky 8 bit screen, you have to do almost nothing in this
  196. routine, but for an AGA driver this is the most hardest part.
  197.  After your screen was opened, your palette was loaded, you have to
  198. convert 8 bit chunky data to your screen. In the emulator screen colors
  199. between 0-127 had been used. You can see: only 7 bit is enough.
  200.  
  201.  Chunky format: one pixel is one byte, 0th. bit is LSB, 6th. bit is MSB and
  202. 7th. is always 0 (hopefully, you can depend on this).
  203.  After finishing the conversion (or anything you do), give back the (next)
  204. address of chunky screen in D0. (You can do easly double buffering on
  205. graphcards.) If you use the same chunky buffer again, then give back that
  206. address.
  207.  
  208.  I see no reason of an MMU based driver, emulator uses line-based screen
  209. emulation, and it refreshes all lines on screen at this time. BTW a delta
  210. buffer would be grateful for slow conversion.
  211.  
  212. * drv_RefreshPPC *
  213.  
  214.  Input:
  215.    A0 - handler
  216.  
  217.  Output:
  218.    D0 - (next) chunky screen
  219.  
  220.  Just like the one before, except this routine must be completely on the
  221. PowerPC part. It will be called without context-switches, thus speeds up the
  222. PPC version. (In the 68k verison will do context switch of course... :) It
  223. should be working exactly the same way as the drv_Refresh does.
  224.  The driver can be in two separated executables, but I see no reason why
  225. would anybody choose this way. WarpUP's mixed binary would be better.
  226.  
  227.  Do not use asynchrone routines here!
  228.  
  229. Contact
  230. -------
  231.  
  232. Any questions and comments are welcome:
  233.  
  234.  racs@fs2.bdtf.hu
  235.  
  236.                  Thank you for supporting Flamingo project!
  237.  
  238. Álmos Rajnai
  239.  
  240.